/**
 * 版权所有(C)，上海海鼎信息工程股份有限公司，2007，所有权利保留。
 * 
 * 项目名：	rumba
 * 文件名：	ICartridgeMgr.java
 * 模块说明：	
 * 修改历史：
 * Apr 26, 2007 - lxm - 创建。
 */
package com.hd123.rumba.cartridge;

import java.util.List;

import net.sf.hibernate.HibernateException;

import com.hd123.rumba.exception.BusinessException;
import com.hd123.rumba.runtime.IManager;
import com.hd123.rumba.runtime.OperateContext;
import com.hd123.rumba.util.Version;

/**
 * 构件包 | 管理员 | 接口类
 * 
 * @author lxm
 * 
 */
public interface ICartridgeMgr extends IManager {

  /**
   * 创建构件包对象。
   * 
   * @return 返回创建的构件包对象。
   * @throws BusinessException
   * @throws HibernateException
   */
  public ICartridge createCartridge() throws BusinessException, HibernateException;

  /**
   * 创建构件包功能视图对象。
   * 
   * @param cartridge
   *          指定构件包功能视图所属构件包。
   * @return 返回创建的构件包功能视图对象。
   * @throws BusinessException
   */
  public ICartFunctionView createFunctionView(ICartridge cartridge) throws BusinessException;

  /**
   * 保存指定的构件包到数据库。
   * 
   * @param cartridge
   *          指定被保存的构件包。
   * @param operate
   * @throws BusinessException
   * @throws HibernateException
   */
  public void saveCartridge(ICartridge cartridge, OperateContext operate) throws BusinessException,
      HibernateException;

  /**
   * 物理删除构件包。
   * 
   * @param cartridge
   *          指定被删除的构件包。
   * @param operate
   * @throws BusinessException
   * @throws HibernateException
   */
  public void removeCartridge(ICartridge cartridge, OperateContext operate)
      throws BusinessException, HibernateException;

  /**
   * 保存指定的构件包功能视图。<br>
   * 将导致对应的构件包功能视图添加一条EntityLog。
   * 
   * @param cfv
   *          指定被保存的构件包功能视图。
   * @param operate
   * @throws BusinessException
   * @throws HibernateException
   */
  public void saveFunctionView(ICartFunctionView cfv, OperateContext operate)
      throws BusinessException, HibernateException;

  /**
   * 物理删除指定的构件包功能视图。<br>
   * 将导致对应的构件包功能视图添加一条EntityLog。
   * 
   * @param cfv
   *          指定被删除的构件包功能视图。
   * @param operate
   * @throws BusinessException
   * @throws HibernateException
   */
  public void removeFunctionView(ICartFunctionView cfv, OperateContext operate)
      throws BusinessException, HibernateException;

  /**
   * 根据uuid取得指定的构件包。
   * 
   * @param uuid
   *          指定构件包的uuid。
   * @return 返回取得的构件包，若找不到返回null。
   * @throws BusinessException
   * @throws HibernateException
   */
  public ICartridge getCartridge(String uuid) throws BusinessException, HibernateException;

  /**
   * 根据前缀取得构件包。
   * 
   * @param prefix
   *          指定构件包的前缀。
   * @return 取得的构件包，若找不到返回null。
   * @throws BusinessException
   * @throws HibernateException
   */
  public ICartridge getCartridgeByPrefix(String prefix) throws BusinessException,
      HibernateException;

  /**
   * 取得指定构件包中的所有功能视图。
   * 
   * @param cartridge
   *          指定的构件包。
   * @return 返回取得功能视图列表，若没有附和条件的功能视图，则返回空列表。
   * @throws BusinessException
   * @throws HibernateException
   */
  public List<ICartFunctionView> getFunctionViews(ICartridge cartridge) throws BusinessException,
      HibernateException;

  /**
   * 根据uuid取得构件包功能视图。
   * 
   * @param uuid
   *          指定构件包功能视图的uuid。
   * @return 返回取得的构件包功能视图，若找不到返回null。
   * @throws BusinessException
   * @throws HibernateException
   */
  public ICartFunctionView getFunctionView(String uuid) throws BusinessException,
      HibernateException;

  /**
   * 根据前缀取得构件包功能视图。
   * 
   * @param prefix
   *          指定构件包功能视图的uuid。
   * @return 返回取得的构件包功能视图，若找不到返回null。
   * @throws BusinessException
   * @throws HibernateException
   */
  public ICartFunctionView getFunctionViewByPrefix(String prefix) throws BusinessException,
      HibernateException;

  /**
   * 取得指定构件包目前数据库的版本号。<br>
   * 本过程不会提交数据库错误，若处理过程中发生数据库错误，比如数据表不存在，则直接返回“0.0.0.0”。
   * 
   * @param cartUuid
   *          指定的构件包的uuid。
   * @return 返回版本号。
   * @throws BusinessException
   */
  public Version getDBVersion(String cartUuid) throws BusinessException;

  /**
   * 开始升级处理。<br>
   * 将在数据库中设置正在升级的标记。对应{@link #endUpgradeT()}可以消除这个升级标记。<br>
   * 若指定的构件包尚未被新增保存到数据库中，该方法将不做任何事，但方法调用仍然成功。
   * 
   * @param cartUuid
   *          指定当前升级构件包的uuid。
   * @throws BusinessException
   * @throws HibernateException
   */
  public void beginUpgradeT(String cartUuid) throws BusinessException, HibernateException;

  /**
   * 结束升级处理。<br>
   * 修改数据库版本号，并标记数据库升级结束。<br>
   * 若不存在相应的构件包记录，将自动新增。
   * 
   * @param cartUuid
   *          指定的构件包的uuid。
   * @param version
   *          指定目标版本号。
   * @throws BusinessException
   * @throws HibernateException
   */
  public void endUpgradeT(String cartUuid, Version version) throws BusinessException,
      HibernateException;
}
